Custom Authentication

Most APIs require authentication of requests. In other words, you will have to involve authenticating the sender of a request and verifying that they have permission to access or manipulate the relevant data via a security context. The REST service specifies the required authorization.

Note: If you are using a commercial REST service, you need to register with that service and get the security context associated with your account.

This section describes how to configure custom authentication.

Setting up the custom configurations depends on the security context provided by the REST service you integrate with. There are services which provide you with one or more security contexts: security token, bearer token, username and organization key, etc.

Some endpoints are authenticated using a bearer token through another endpoint, in case you need to get the security context (Step 1). Others authenticate with a fixed bearer token, which means that you do not need to get it nor check its validity (skip steps 1 and 3). You can however, put the token in a template and use it for all API calls (Step 2).

Step 1: Get the security context

For APIs that use security token or bearer token for authentication, define the REST call to get the security access / bearer token.

For example, you integrate with a third party API which uses a bearer token for authentication and obtaining that bearer token requires you to use your user name and organization key for authentication.

There are also REST APIs that besides access tokens allow you to optionally obtain a refresh token and use it to obtain a new access token when the current access token becomes invalid or expires.

Understand the security context

This section provides information to help you understanding how the authentication and authorization works with access and refresh tokens.

DRUID makes an initial API call and requests an access token by authenticating with the authorization server and presenting an authorization grant (user name & password or organization key, API key & API Secret, etc.).
The authorization server authenticates the client and validates the authorization grant, and if valid, issues an access token and (if requested) a refresh token.
DRUID makes a protected resource request to the resource server by presenting the access token.
The resource server validates the access token, and if valid, serves the request.
Steps (3) and (4) repeat until the access token expires. If DRUID knows that the access token expired, it skips to step (8); otherwise, it makes another protected resource request.
Since the access token is invalid, the resource server returns an invalid token error.
DRUID requests a new access token by authenticating against the authorization server and presenting the refresh token instead. The authentication requirements depend on the client type and on the authorization server policies.
The authorization server authenticates DRUID and validates the refresh token, and if valid, issues a new access token (optionally, as per authorization server policy, generates a new refresh token as well).

Define the Authenticate Client connector action

In the REST connector configuration page, click the + icon next to the AuthenticateClientConnectorAction field. The Connector Action page appears on the ConnectorGeneral tab. Fill-in all the mandatory fields, then click Save.

The page refreshes and displays on the ConnectorSteps tab.

At the top-right corner of the page, click the Create Task button and select Authenticate Client.

The Edit Connector Action page appears on the General tab.

Define the Authenticate Client integration task

Enter a Description and from the Connection Code drop-down, select the REST connector.

Click the Request tab and configure the request.

If you want to authorize subsequent REST API calls using refresh tokens instead of using credentials, you can do so by selecting Use refresh token pattern and then configuring the authentication call following the steps below. If you don't want to use refresh tokens, do not select Use refresh token pattern and follow only steps 1 and 2.

Step 1. Configure the main authentication call request (Authenticate Client Request)

DRUID makes an initial API call (main authentication call) and requests an access token by authenticating with the authorization server and presenting an authorization grant (user name & password or organization key, API key & API Secret, etc.).

To configure the main authentication call, click the Authenticate Client Request. If you are not using the refresh token pattern, the tab displays by default.

Make a request to your authentication endpoint (as required by the API). Set the Parameters, Headers or Body with the values appropriate to your authentication API. Use integration context variables to securely refer credentials, like username, API keys, passwords etc., using the “@” symbol.

Note: Define the integration context variables in clear on the connector app and refer them on the integration tasks using the "@" SYMBOL.

Step 2. Configure the response of the main authentication call (Authenticate Client Request)

The authorization server authenticates the client and validates the authorization grant, and if valid, issues an access token and (if requested) a refresh token.

To configure the response of the main authentication call, click the Response tab. Click the Authenticate Client Request tab. If you are not using the refresh token pattern, the tab displays by default. Map the received access token / key within a variable. This new variable (e.g., @ApiToken) is automatically defined by simply mentioning it in the response mapping table; there is no need to define it somewhere else.

Important! DRUID will keep this variable in-memory until it will be used in Step 2 (authorization) and it must not interfere with other connector task variables; therefore, make sure that you provide an unique variable name (a name different than the integration context variables set at Step 1).

If you're using the refresh token pattern, in the response mapping table, edit the first table entry by mentioning the Connector field name that holds the refresh token. DRUID Connector will store the refresh token in a dedicated asset storage and will automatically set the value of the refresh token at runtime, when needed. That is why the first row in the mapping table is generated automatically, cannot be deleted and is mandatory to be filled in (in Connector field name) for this pattern.

Note: If the token is returned as a simple string, in the Connector field type, specify text. Support for tokens returned as string IS AVAILABLE IN druid 5.14 and higher.

Step 3. Configure the refresh token request

DRUID requests a new access token by authenticating with the authorization server and presenting the refresh token.

To configure the refresh token request, click the Request tab, then click the Refresh Token Request tab.

Configure a request to your refresh token  endpoint (or authentication endpoint as required by the API). Set the Parameters, Headers or Body with the values appropriate to your refresh token API.

In the mapping table, click the Edit icon displayed in line with the first row and in the ConnectorFieldName field, provide the name of the field indicated by the API endpoint where DRUID will automatically set at runtime the refresh token obtained after executing the first authorization call (step 2). This way all API calls will be authorized using the refresh token instead of the access token.

Step 4. Configure the refresh token response

The authorization server authenticates DRUID and validates the refresh token, and if valid, issues a new access token (optionally, as per authorization server policy, generates a new refresh token as well).

To configure the refresh token response, click the Response tab, then click the Refresh Token Response tab.

Map the access token / key within a variable. This new variable (e.g., @ApiToken) is automatically defined by simply mentioning it in the response mapping table; there is no need to define it somewhere else. Use the variable you use in general to hold the access token.

If Authorization Server also returns a new refresh token, select Response contains a new Refresh Token and in the response mapping table, edit the first table entry by mentioning the ConnectorFieldName that holds the new refresh token. DRUID Connector will automatically set the new value of the refresh token at runtime (the value of the refresh token obtained after executing the first authorization call).

If Authorization Server does not generate a new refresh token (reset the refresh token - Response contains a new Refresh Token is not selected), and the refresh token expires or becomes invalid, you can select the corresponding error code from Invalid Refresh token HTTP code response, which is returned by Authorization Server in this case Whenever an API call is done with an invalid / expired refresh token, DRUID connector receives the selected error code and automatically obtains another access and refresh token, by executing step 1 again.

Click the Save&Close twice to save the task and the connection action.

Select the call for getting the security context

Go to Apps and click on the REST connector you want to configure. From the AuthenticateClientConnectorAction drop-down, select the call for getting the security token.

Click the Save button to save the connector configuration.

Step 2: Define authorization template for all API calls

The DRUID ChatBot Platform enables you to configure the API call template with the authorization info, which will be used in all integrations referring the specific App.

In the Connector configuration page, click the + icon next to the AuthorizeRequestConnectorAction field. The Connector Action page appears on the ConnectorGeneral tab. Fill-in all the mandatory fields, then click Save.

The page refreshes and displays on the ConnectorSteps tab.

At the top-right corner of the page, click the Create Task button and select Authorize Request.

The Edit Connector Action page appears on the General tab.

Enter a Description and from the Connection Code drop-down, select the REST connector.

Click the Save button to save the settings, then at the top-right corner of the page, click the Request tab. By default, it appears on the Headers tab.

In the Headers table or in the Body, enter the security context obtained in Step 1 (if applicable), or directly fixed values defined as integration context variables (APP variables). Refer them by using the “@” symbol. (@ApiToken or @ApiKey , @ApiSecret, etc.).

Note: At runtime, this token will be placed on the main integration task, as it is configured in Authorization Action (Step 2), either in the header of body, on EVERY execution of the main integration task.

Example of using the token for Bearer or Basic authentication types

Use DRUID build in function concat()as follows: concat('Bearer',@token). Use the token type (Basic/Bearer) followed by space followed by the token:

Basic

Save the Save&Close twice to save the task and the connection action.

Go to Apps and click on the REST connector you want to configure. From the AuthorizeRequestConnectorAction drop-down, select the security template.

Click the Save button to save the connector configuration. Although not visible in the DRUID ChatBot Portal, the security template will be automatically added to the header of all requests using the connector.

Step 3: Set responses when authentication is required

Note: Perform this step only if you’re calling the API to get the security context (Step 1).

Define the response template in case the security context expires (and the request is unauthenticated). To do so, click the + icon next to the CheckNotAuthenticatedConnectorAction field. The Connector Action page appears on the ConnectorGeneral tab. Fill-in all the mandatory fields, then click Save.

The page refreshes and displays on the ConnectorSteps tab.

At the top-right corner of the page, click the Create Task button and select Check If Not Authenticated.

The Edit Connector Action page appears on the General tab.

Enter a Description.

Click the Save button to save the settings, then at the top-right corner of the page, click the Response tab.

You have two options to define the error code for unauthenticated requests:

Using HTTP status codes. To do so, from the HttpStatusCode field, select the error code to be returned in case the request is not authenticated.

Using API specific response. We strongly recommend you to use choose this option whenever the API returns the response message in JSON format asking you to renew the security token. To do so, click the Body tab and provide the expected API response.

Click the Save&Close twice to save the task and the connection action.

Go to Apps and click on the REST connector you want to configure. From the CheckNotAuthenticatedConnectorAction drop-down, select the response for unauthenticated requests.

Click the Save & Close button to save the connector configuration.

Note: This action will only be executed if the response of the main integration task returns an error or a specific response body, as defined here. If the error code or response body returned is the same with the ones defined in Step 3, then the Authentication Action will be automatically called again to get a new authentication context and it will be re-used in step 2, until a successful response is obtained from the main integration task.